/*
 *  StopMemory.java
 *
 *  Chau, Sau Ming
 *
 *  August 14, 2000
 *
 *  This file defines the StopMemory class. StopMemory and together with
 *  DocMemory (defined in DocMemory.java) are a Java wrapper to the C
 *  implementation (WinNT) of the Extractor algorithms developed at NRC by
 *  Peter Turney. For more information about Extractor, visit
 *  http://extractor.iit.nrc.ca. This implementation uses Extractor 6.0.
 *  This is an extention of Extractor.java (first Java wrapper to Extractor)
 *  developed at NRC by Marvin Zaluski.
 *
 *  What is added
 *    - allow multiple documents processed in a single- or multi-thread
 *      environment.
 *
 *  StopMemory oblect contains a pointer (or address) to memory storing stop
 *  words and stop phrases.  It provides functions accessing and manipulating
 *  the content of stop memory (e.g. AddStopWord()).
 *
 *  Dependencies: For example, ClearStopMemory() should only be called
 *  after CreateStopMemory has been called. For efficiency reasons,
 *  Extractor does not verify that the functions are called in the
 *  correct order. The programmer is responsible for ensuring that the
 *  dependencies are observed in the program that invokes Extractor.
 *  Please refer to http://extractor.iit.nrc.ca for details.
 *
 *  - Important -  Class path containing the Extractor Wrapper dll or so
 *  must be specified in order to function properly.  For example, in WinNT,
 *  go to Control Panel -> System -> Environment and type the path
 *  (e.g. C:\App) in Class path text box.  For more information
 *  about setting class path, please refer to Java website java.sun.com.
 */
 
/*
 *  Modified by Peter Turney
 *
 *  August 10, 2001
 */

public class StopMemory
{
  //  Character Code ISO-8859-1
  public final static int CharCodeISO_8859_1 = 0;
  
  //  Character Code MS-DOS
  public final static int CharCodeMS_DOS = 1;
  
  //  Character Code Unicode-UCS2
  public final static int CharCodeUnicode_UCS2 = 2;
  
  //  Character Code Shft-JIS
  public final static int CharCodeShft_JIS = 3;
  
  //  Character Code JIS
  public final static int CharCodeJIS = 4;
  
  //  Character Code EUC-jp
  public final static int CharCodeEUC_jp = 5;

  //  Language ID for Automatic Language Detection
  public final static int LanguageAUTOMATIC = 0;
  
  //  Language ID for English Language Detection
  public final static int LanguageENGLISH = 1;
  
  //  Language ID for French Language Detection
  public final static int LanguageFRENCH = 2;
  
  //  Language ID for Japanese Language Detection
  public final static int LanguageJAPANESE = 3;
  
  //  Language ID for German Language Detection
  public final static int LanguageGERMAN = 4;

  //  Default Highlight Type
  public final static int Highlight00000000 = 0;
  
  //  Highlight Type - Remove Duplicate Sentences Highlight Type
  public final static int Highlight00000001 = 1;
  
  //  Highlight Type - Order Of Appearance In Text Highlight Type
  public final static int Highlight00000010 = 2;
  
  //  Highlight Type - Use Full Sentence Highlight Type
  public final static int Highlight00000100 = 4;
  
  //  Highlight Type - Markup Important Words Highlight Type
  public final static int Highlight00001000 = 8;
  
  //  Highlight Type - Markup Unimportant Words Highlight Type
  public final static int Highlight00010000 = 16;

  
  private long lng_stop_mem_ptr;    // Pointer to stop memory
  private boolean bln_valid;        // Indicate validity of StopMemory object
  private int int_last_return_code; // Return code of last operation

 
  /*
   *  StopMemory
   &
   *  Constructor
   *
   *  Arguments
   *    - none
   *
   *  Return
   *    - none
   *
   *  public StopMemory()
   */
  public StopMemory()
  {
    lng_stop_mem_ptr = -1;  // Invalid pointer value
    bln_valid = false;      // Not properly constructed
    CreateStopMemory();     // Create a stop memory through Extractor
  }

  
  /*
   *  GetStopMemoryPointer
   *
   *  Return the stop memory pointer.
   *
   *  Arguments
   *    - none
   *
   *  Return
   *    - (long) stop memory pointer
   *
   *  public long GetStopMemoryPointer()
   */
  public long GetStopMemoryPointer()
  {
    return lng_stop_mem_ptr;
  }

  
  /*
   *  isValid
   *
   *  Return true if StopMemory object is properly constructor; otherwise,
   *` return false.
   *
   *  Arguments
   *    - none
   *
   *  Return
   *    - (boolean) validity of this StopMemory object
   *
   *  isValid()
   */
  public boolean isValid()
  {
    return bln_valid;
  }

  
  /*
   *  GetReturnCode
   *
   *  Return the return code of last operation.  For more information, please
   *  refer to http://extractor.iit.nrc.ca/api.html.
   *
   *  Arguments
   *    - none
   *
   *  Return
   *    - (int) return code of last operation
   *  
   *  public int GetReturnCode()
   */
  public int GetReturnCode()
  {
    return int_last_return_code;
  }

  
  /*
   *  CreateStopMemory
   *
   *  Create a stop memory only if it is not properly constructed (i.e.
   *  stop memory not yet created by Extractor through native method
   *  CreateStopMemory_helper()).
   *
   *  Arguments
   *    - none.
   *
   *  Return
   *    - (int) return code from Extractor
   *
   *  public int CreateStopMemory()
   */
  public int CreateStopMemory()
  {
    if (!bln_valid)
    { // Create stop memory through CreateStopMemory_helper().
      if ((int_last_return_code = CreateStopMemory_helper()) == 0)
      { // Stop memory created successfully.
        bln_valid = true;
      }
    }
    else
    { // Stop memory already created.
      int_last_return_code = 0;
    }
    return int_last_return_code;
  }

  
  /*
   *  ClearStopMemory
   *
   *  Clear the stop memory and free up space used by stop memory.  It is
   *  done only if the StopMemory is properly constructed.
   *
   *  Arguments
   *    - none
   *
   *  Return
   *    - (int) return code from Extractor
   *
   *  public int ClearStopMemory()
   */
  public int ClearStopMemory()
  {
    if (bln_valid)
    { // Stop memory is constructed.
      int_last_return_code = ClearStopMemory_helper(lng_stop_mem_ptr);
      if (int_last_return_code == 0)
      {
        lng_stop_mem_ptr = -1;
        bln_valid = false;
      }
    }
    else
    {
      int_last_return_code = 0;
    }
    return int_last_return_code;
  }

  
  /*
   *  GetErrorMessage
   *
   *  Return error message correspond to the input error code number.
   *
   *  Arguments
   *    1. (int) error code
   *
   *  Return
   *    - (String) error message
   *
   *  GetErrorMessage(int errorCode)
   */
  public String GetErrorMessage(int errorCode)
  {
    if (errorCode == 0)
    {
      return new String("ERROR: All is OK. No errors were detected.");
    }
    else if (errorCode > 0)
    {
      return GetErrorMessage_helper(errorCode);
    }
    else
    {
      return new String("ERROR: Error Code is UNKNOWN.");
    }
  }

  
  /*
   *  AddStopWord
   *
   *  Add a stop word to stop memory.  This function is optional.  Language ID
   *  and character code ID must be specified in argument list.  For more
   *  information, please refer to http://extractor.iit.nrc.ca/api.html or
   *  static variables description.  Notice that character code ID for
   *  Unicode UCS2 (2) is not supported in this function as it does not
   *  convert the stop word (in String) characters to double byte.
   *
   *  Arguments
   *    1. (int) language ID
   *    2. (int) character code ID (Unicode is not supported)
   *    3. (String) stop word 
   *
   *  Return
   *    - (int) return code from Extractor
   *
   *  public int AddStopWord(int LanguageID, int CharCodeID, String Word)
   */
  public int AddStopWord(int LanguageID, int CharCodeID, String Word)
  {
    // strings in C must be null terminated
    String NullWord;
    NullWord = Word + "\0";
    // Call the native method AddStopWord_helper()
    return AddStopWord_helper(lng_stop_mem_ptr, LanguageID, CharCodeID, NullWord.getBytes());
  }
  
  
  /*
   *  AddStopWord
   *
   *  Add a stop word to stop memory.  This function is optional.  Language ID
   *  and character code ID must be specified in argument list.  For more
   *  information, please refer to http://extractor.iit.nrc.ca/api.html or
   *  static variables description.  Extractor handles Unicode UCS2 characters
   *  using the byte ordering of the hardware for which it is compiled
   *  (native byte ordering). Therefore, the byte array of stop word must be
   *  correctly ordered in UCS2 case.
   *
   *  Arguments
   *    1. (int) language ID
   *    2. (int) character code ID (Unicode is not supported)
   *    3. (String) stop word 
   *
   *  Return
   *    - (int) return code from Extractor
   *
   *  public int AddStopWord(int LanguageID, int CharCodeID, byte[] Word)
   */
  public int AddStopWord(int LanguageID, int CharCodeID, byte[] Word)
  {
    // strings in C must be null terminated
    byte[] NullWord = new byte[Word.length + 1];
    System.arraycopy(Word, 0, NullWord, 0, Word.length);
    NullWord[Word.length] = (byte) 0;
    // Call the native method AddStopWord_helper()
    return AddStopWord_helper(lng_stop_mem_ptr, LanguageID, CharCodeID, NullWord);
  }

  
  /*
   *  AddStopPhrase
   *
   *  Add a stop word to stop memory.  This function is optional.  Language ID
   *  and character code ID must be specified in argument list.  For more
   *  information, please refer to http://extractor.iit.nrc.ca/api.html or
   *  static variables description.  Notice that character code ID for
   *  Unicode UCS2 (2) is not supported in this function as it does not
   *  convert the stop word (in String) character to double byte.
   *
   *  Arguments
   *    1. (int) language ID
   *    2. (int) character code ID (Unicode is not supported)
   *    3. (String) stop phrase
   *
   *  Return
   *    - (int) return code from Extractor
   *
   *  public int AddStopWord(int LanguageID, int CharCodeID, String Phrase)
   */
  public int AddStopPhrase(int LanguageID, int CharCodeID, String Phrase)
  {
    // strings in C must be null terminated
    String NullPhrase;
    NullPhrase = Phrase + "\0";
    // Call the native method AddStopPhrase_helper()
    return AddStopPhrase_helper(lng_stop_mem_ptr, LanguageID, CharCodeID, NullPhrase.getBytes());
  }
  
  
  /*
   *  AddStopPhrase
   *
   *  Add a stop phrase to stop memory.  This function is optional.  Language ID
   *  and character code ID must be specified in argument list.  For more
   *  information, please refer to http://extractor.iit.nrc.ca/api.html or
   *  static variables description.  Extractor handles Unicode UCS2 characters
   *  using the byte ordering of the hardware for which it is compiled
   *  (native byte ordering). Therefore, the byte array of stop word must
   *  be correctly ordered in UCS2 case.
   *
   *  Arguments
   *    1. (int) language ID
   *    2. (int) character code ID (Unicode is not supported)
   *    3. (String) stop phrase
   *
   *  Return
   *    - (int) return code from Extractor
   *
   *  public int AddStopPhrase(int LanguageID, int CharCodeID, byte[] Phrase)
   */
  public int AddStopPhrase(int LanguageID, int CharCodeID, byte[] Phrase)
  {
    // strings in C must be null terminated
    byte[] NullPhrase = new byte[Phrase.length + 1];
    System.arraycopy(Phrase, 0, NullPhrase, 0, Phrase.length);
    NullPhrase[Phrase.length] = (byte) 0;
    // Call the native method AddStopPhrase_helper()
    return AddStopPhrase_helper(lng_stop_mem_ptr, LanguageID, CharCodeID, NullPhrase);
  }

  
  /*
   * -------------------------------------------------------------------------
   *
   *  The following are the native methods accessing Extractor dll (WinNT)
   *  or so (Unix).
   *
   * -------------------------------------------------------------------------
   */

  private native int CreateStopMemory_helper();

  private native int ClearStopMemory_helper(long StopMemory);

  private native String GetErrorMessage_helper(int errorCode);

  private native int AddStopWord_helper(long StopMemory, int LanguageID,
                                          int CharCodeID, byte[] Word);

  private native int AddStopPhrase_helper(long StopMemory, int LanguageID,
                                            int CharCodeID, byte[] Phrase);
}